Skip to content

refactor(server): one route handler for REST, MCP, download links and serve - #739

Merged
eizedev merged 2 commits into
mainfrom
refactor/route-handler
Nov 22, 2026
Merged

eizedev merged 2 commits into
mainfrom
refactor/route-handler

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

Step 3 of the layering rework: one route handler instead of four copies of the per-request wrapper.

What changed

  • One route handler. createRouteHandler(context, family) lives in packages/pivotkit-server/src/route-handler.js. pivotkit-mcp gets it through pivotkit-server/internal. It is the one copy of what every route family did per request:
    • the request's scope (requestScopeFor), kept in info
    • the refused line of an error answer that wrote none (logUnanswered)
    • X-Request-Id on every answer
    • the answer to a body that cannot be read
  • What each family supplies. check and answer are required. familyOf, finish (REST: the id in a problem body), release (REST: the large-body place) and unreadable are optional. trustProxy and the log come from the context.
  • The four families:
    • rest/handler.js, pivotkit-mcp's http.js and serve.js keep only their check and answer.
    • downloads.js became a family of its own. Its hosts (serve, pivotkit-mcp) now pass their info on to downloads.precheck, fetch and problem, so both name one request id. The download family's entry in the hosts' routeFamily is gone. The download links name their family once (DOWNLOAD_FAMILY).
  • One plainAddress. As you asked, the two copies are now one. listen.js reads socket addresses with request-id.js's plainAddress, now exported.
    • The listen.js copy stripped any ::ffff: prefix. The request-id.js copy strips it only before a dotted IPv4.
    • listen.js only gets socket.remoteAddress. Node writes a mapped address there in dotted form, so both copies gave the same result.
    • The hex form ::ffff:7f00:1 would differ, but no socket gives it. Even then isLoopback refused both results.
  • The three network-code lists (TRANSIENT, NETWORK_CODES, NETWORK_TEXTS) go into step 4. They are about which errors are transient and how they are worded, which is that step's topic.

Behaviour: no change for any request through serve, pivotkit-mcp or REST

  • REST: the same order as before. The log line comes first, then the id in the problem body, then the header, then the release. In the unreadable-body answer: release, then the cap through peekSignIn, then the log line.
  • MCP and serve: the same answers and lines. A download 404 is still logged once at info. The inner family marks the request's line as written, so the host writes none.
  • serve's default info was { address: "" }, now {}. Both give a scope without an address.
  • trustProxy is read from context.options. That is the object each family read before, serve included: createContext keeps the options it is given.

A difference that only shows outside these hosts: createDownloadHandler(...).fetch(request) called without a host now makes a scope of its own, with an address and an X-Request-Id. Before, it ran under requestId() ?? newRequestId(). Every caller in this repository passes info, and pivotkit-server/internal is not public interface (docs/versioning.md).

Release note

pivotkit-mcp now imports createRouteHandler from pivotkit-server/internal. A pivotkit-mcp of this release needs the pivotkit-server of this release. serve already refuses a pivotkit-mcp whose imports this pivotkit-server lacks, and names both versions. The pivotkit-server range of pivotkit-mcp must be raised when the release is cut. RELEASING.md already says to release pivotkit-server first.

Not part of this change (say what does not fit)

  • Two places route an unreadable body to its family, download or other: serve.js problem and pivotkit-mcp's listen().
  • A download request runs its Host and size check twice: once in the host's precheck and once in its fetch. That keeps a host that skips the precheck safe. Before this change it ran twice too.

Growth (scripts/growth.js measures, before → after)

before after
functions over 120 lines 48 47 (createServerHandler is below the limit now)
createHttpHandler (mcp) 173 lines 160
createRestHandler 357 lines 351
createDownloadHandler 445 lines 443 (complexity 26, unchanged)
functions over complexity 25 105 105
unused exports and files (knip) 222 222
jscpd clones / duplicated lines 231 / 1631 (0.31%) 218 / 1566 (0.30%)
docs lines 25820 25820

scripts/growth-baseline.json is lowered in this pull request.

Checks

  • npm run lint, npm run types, npm test (all workspaces and tests/), npm run growth, npm run pack:check: green locally.
  • The server, CLI and MCP integration tests are part of npm test.
  • No browser tests: no UI is touched.
  • test/route-handler.test.js covers the handler:
    • one id across precheck, fetch and the unreadable-body answer
    • a hosted family naming the host's id and writing one line
    • no second line when the route wrote its own
    • release on success, on an unreadable body and on a thrown route
    • trustProxy
    • plainAddress
  • A neutral review judged the whole files. It found no behaviour change for hosted traffic. Its follow-ups are in:
    • serve takes only precheck and fetch
    • one info typedef
    • the tests above
    • the request-id.js header
    • the changelog wording

Places checked for docs:

  • pivotkit-server AGENTS.md ("HTTP edge")
  • the server and MCP CHANGELOGs
  • the request-id.js header

docs/reference/service-exports.md needs no change, because only internal grew. pivotkit-mcp's AGENTS.md needs no change.

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 21:38
… serve

The request's scope, the refused line of an unlogged error answer, X-Request-Id and the
answer to an unreadable body were written out in rest/handler.js, pivotkit-mcp's http.js,
downloads.js and serve.js. createRouteHandler in route-handler.js is now the one copy;
each family supplies its check, its answer and its unreadable-body answer. Hosts pass
their info on to the download links, so both name one request id. listen.js reads socket
addresses with request-id.js's plainAddress instead of a copy of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es and plainAddress

Review follow-ups: serve takes only precheck and fetch from its route handler, the
info typedef matches the hosts', tests cover a hosted family's id and line, release on
a thrown route, and plainAddress.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit 8746674 into main Nov 22, 2026
25 checks passed
@eizedev
eizedev deleted the refactor/route-handler branch November 22, 2026 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant